# Hermes LCARS Dashboard - Read Me First

Built by Moddy - http://www.moddys.net

This is the LCARS theme for the Hermes Agent web dashboard. After you unzip
the download, EVERYTHING IS ALREADY HERE AND READY TO INSTALL. You do NOT
need to unpack anything else - there is no second .zip to open.

------------------------------------------------------------
WHAT YOU SHOULD SEE IN THIS FOLDER
------------------------------------------------------------

    apply.py              - the installer script
    apply_lcars_skin.py   - the skin engine (used by apply.py)
    run.bat              - Windows launcher  (double-click this)
    run.sh               - macOS / Linux launcher (double-click it)
    lcars_autoheal.py    - auto-heal watchdog (re-skins after a Hermes update)
    lcars-bg.jpg         - the main wallpaper picture
    lcars-bg/            - the 12 theme wallpaper pictures
    python/              - Python installers (used only if Python is missing)
    assets/              - licensing / attribution notes
    LICENSE              - the MIT license
    SECURITY.md          - security & privacy notes
    read me.txt          - this file

That is the complete package. Nothing else needs extracting.

------------------------------------------------------------
ONE-TIME: UNPACK
------------------------------------------------------------

1. Make a new, empty folder anywhere on your computer.
   The Desktop is easiest - for example:  Desktop/Hermes-LCARS/

2. Put the .zip you downloaded into that folder, then EXTRACT it there.

   - Windows: right-click the .zip -> "Extract All..." -> choose the new folder.

   - macOS:   double-click the .zip. macOS unzips it automatically into your
              Downloads folder (a new folder appears there). To keep things
              tidy, first make a folder on your Desktop (e.g. Hermes-LCARS),
              then move the downloaded .zip into it and double-click the .zip
              - the extracted folder will appear inside it. Or, after macOS
              extracts it to Downloads, just drag that new folder to your
              Desktop.

   - Linux:   unzip the .zipto the new folder you just made. (or right-click -> Extract..path to new folder).

3. Open the folder you just extracted. You should see the files listed
   above (apply.py, run.bat, run.sh, lcars-bg/, python/, etc.).

------------------------------------------------------------
INSTALL
------------------------------------------------------------

WHAT THE INSTALLER CHECKS (all platforms)
------------------------------------------------------------

Before it changes anything, the installer checks itself first:

  - every file it needs is present and not damaged (skin engine, bridge
    photo, theme wallpapers),
  - Python 3.8 or newer is available (it installs it from the python/
    folder if not - no internet needed),
  - your Hermes dashboard (web_dist/index.html) is found - it checks the
    usual places first, then SEARCHES THIS PC for it,
  - the file it found really is a Hermes dashboard (it never touches a file
    it can't verify).

If something is missing, a pop-up tells you exactly what is needed and how to
get it, and opens the right help page for you. Missing Hermes? It points you to
the Hermes install page. Damaged installer files? It points you back to the
Releases page for a fresh download.

WINDOWS
  Double-click  run.bat
  (If Python isn't installed, it opens the Python installer automatically -
   you may see a brief "allow this app?" prompt, then run.bat waits and
   continues on its own once Python is ready.)

macOS
  Double-click  run.sh
  (If Python isn't installed, it opens the Python installer - you'll be asked
   for your password to allow the install, then run.sh waits and continues on
   its own once Python is ready.)

  NOTE: If double-clicking run.sh doesn't work (it opens Terminal but shows
  a "permission denied" error), right-click run.sh and choose "Open", or
  open Terminal, navigate to this folder, and type:  bash run.sh
  The script auto-fixes its own permissions when it detects them as missing.

Linux
  Open a terminal inside this folder and run:
     bash run.sh
  (If Python is missing, install it:  sudo apt install python3  (Debian/Ubuntu)
   or  sudo dnf install python3  (Fedora), then run  bash run.sh  again.

------------------------------------------------------------
DONE
------------------------------------------------------------

Refresh your Hermes dashboard in the browser at:

     http://127.0.0.1:9119/sessions

------------------------------------------------------------
LINUX - NEVER USED A TERMINAL BEFORE? (plain steps)
------------------------------------------------------------

This is written for someone who has never opened a terminal. Take it slow -
every line you type is shown exactly as it should appear.

Step 1 - Get the files
  You downloaded a .zip file. Make a new, empty folder (the Desktop is
  easiest). Put the .zip into it and extract it (right-click -> Extract Here,
  or  unzip file.zip). You now have a folder with apply.py, run.sh, lcars-bg/,
  python/, and this read me in it. Remember where it is.

Step 2 - Open a terminal
  A terminal is the window where you type commands. Open it one of these ways:
   - Press the Super/Windows key, type  terminal, and press Enter; or
   - Right-click the desktop or a folder and choose "Open in Terminal".
  You will see a prompt ending in  $  - that means it is ready for typing.

Step 3 - Go into the folder
  The terminal starts in your home folder. Move into the extracted folder.
  Type this (change the name if yours is different), then press Enter:

     cd Downloads/hermes-lcars-dashboard

  Tip: you can type  cd Down  and press Tab to auto-complete the rest.
  To check you are in the right place, type  ls  and press Enter - you should
  see  apply.py, run.sh, lcars-bg.jpg, the python/ folder, and so on.

Step 4 - Run the installer
  Type this and press Enter:

     bash run.sh

  That is it. run.sh is a small script that:
   - checks whether Python 3 is installed,
   - if it is, skins your Hermes dashboard right away,
   - if it is NOT, helps you install Python ( sudo apt install python3 -
     you will be asked for your password), then waits and continues on its
     own once Python appears.

Step 5 - See the result
  Open or refresh your Hermes dashboard in your browser
  ( http://127.0.0.1:9119/sessions ). It should now show the LCARS theme.

If something goes wrong
  - "command not found: bash" - almost never happens; bash is built into Linux.
  - "python3: command not found" - run.sh will tell you to install Python with
     sudo apt install python3  (Debian/Ubuntu/Mint) or
     sudo dnf install python3  (Fedora), then run  bash run.sh  again.
  - Prefer to run it by hand? After Step 3, just type  python3 apply.py .

Step 6 - Later: revert or remove
  Open a terminal in the folder (Steps 2-3) and run:

     python3 apply.py --restore      # go back to your old dashboard
     python3 apply.py --remove        # take the theme off completely

------------------------------------------------------------
REVERT / REMOVE (all platforms)
------------------------------------------------------------

     python3 apply.py --restore      # back to your old dashboard
     python3 apply.py --remove        # remove the theme entirely

The skin never touches your Hermes config, sessions, or keys, and it backs up
your current dashboard automatically before the first apply - so --restore
returns you to exactly how it looked. Backups are stored BOTH next to the
bundle (backups/) AND mirrored into Hermes' data folder (lcars-backups/), so
they survive you moving or deleting the installer folder.

Troubleshooting readout (changes nothing):
     python3 apply.py --check
prints a plain report of what the installer needs and whether it is all there.

------------------------------------------------------------
AUTO-HEAL (survives Hermes updates)
------------------------------------------------------------

Hermes updates overwrite the dashboard file (web_dist/index.html), which would
strip the LCARS skin. This skin is built to recover automatically - you never
have to re-run anything by hand after an update.

Two layers protect it:

  1. LAUNCH RE--APPLY - just open run.bat / run.sh again (or it runs on your
     normal launch) and it re-skins the dashboard. Safe to run any time; it is
     idempotent and will not double-apply.

  2. SCHEDULED WATCHDOG - a small script (lcars_autoheal.py) checks the
     dashboard and puts the skin back whenever it is missing. When the skin is
     already present it stays completely silent.

     The installer registers an OS-level check for you on every platform, so
     there is nothing to set up and nothing to remember:

       Windows   scheduled task  LCARS_Dashboard_AutoHeal          (every minute)
       macOS     LaunchAgent     com.moddyswag.lcars-autoheal       (every minute)
       Linux     systemd user timer  com.moddyswag.lcars-autoheal.timer

     Why an OS scheduler and not just a Hermes cron job? Hermes' cron ticker
     only runs inside a live gateway or desktop backend, and a Hermes update
     stops those processes - which is exactly when the dashboard file gets
     overwritten. All three of the above run outside Hermes entirely, using a
     normal Python install (never the Hermes venv, since that is what an update
     replaces), so the theme returns within about a minute even if you had to
     close everything - gateway, dashboard, every hermes.exe - before updating.

     You can still also use a Hermes cron job as an extra layer if you like:

       hermes cron create "*/30 * * * *" \
         --name "LCARS dashboard auto-heal" \
         --script "lcars_autoheal.py" \
         --no-agent --deliver local

     (It only ticks while a gateway or the desktop app is running, so it is a
     backstop rather than the main protection.)

  Every time you run run.bat / run.sh / apply.py, the latest version of
  lcars_autoheal.py is auto-copied into Hermes' scripts folder(s) — for the
  main install AND every profile — so the watchdog always runs the current
  code, no matter which profile you registered the job from. A small
  location file (lcars_install_dir.txt) is written alongside it so the
  watchdog can find this installer bundle wherever you extracted it
  (Desktop, Downloads, anywhere) — no manual copy or path editing needed. The
  Windows task is re-registered if it is missing or points somewhere else.

  Hermes cron jobs are preserved across `hermes update`, so the watchdog keeps
  working on Windows / macOS / Linux after every update.

  NOTE for upgrades from an older bundle: the watchdog used to be a shell
  script (lcars_autoheal.sh). Hermes runs a cron job's .sh through WSL on
  Windows, so on a machine without a WSL distribution that job failed on every
  tick ("Windows Subsystem for Linux has no installed distributions") while
  looking like a bug in the script itself. The Python version has no such
  dependency, and this installer now retires the old .sh and re-points any
  existing job at lcars_autoheal.py automatically.

Checking it
  python3 apply.py --check        # one line: how the skin recovers after an update
  Windows:  schtasks /Query /TN LCARS_Dashboard_AutoHeal
  macOS:    launchctl list | grep lcars           (or: ls ~/Library/LaunchAgents)
  Linux:    systemctl --user list-timers | grep lcars
  hermes cron list                # only if you also added the Hermes cron job

Turning it off
  python3 apply.py --remove       (or --restore) pauses auto-heal for you: the
  OS-level check is removed and a stand-down marker stops the watchdog, so the
  theme stays off until you run the installer again.
  By hand:
    Windows:  schtasks /Delete /TN LCARS_Dashboard_AutoHeal /F
    macOS:    launchctl bootout gui/$UID ~/Library/LaunchAgents/com.moddyswag.lcars-autoheal.plist
    Linux:    systemctl --user disable --now com.moddyswag.lcars-autoheal.timer
              rm ~/.config/systemd/user/com.moddyswag.lcars-autoheal.{service,timer}
    hermes cron remove <job-id>     (only if you added the Hermes cron job)

  One Linux note: a user timer runs while you are logged in. If you want it to
  fire even before you log in after a reboot, enable lingering for your account:
      sudo loginctl enable-linger $USER

When it has to act, the watchdog writes a line to lcars_autoheal.log next to the
script in Hermes' scripts folder. Silence there means it never needed to do
anything; a warning line is the first thing to send if a theme comes back wrong.

(If you prefer not to use any scheduled job, layer 1 - re-running the launcher
after an update - is enough to restore the theme.)

------------------------------------------------------------
UPDATING HERMES (and the "another hermes.exe is running" error)
------------------------------------------------------------

The skin is not part of Hermes, so it never blocks an update - and you never
have to reinstall it afterwards. If `hermes update` refuses to run:

  ✗ Another hermes.exe is running:  PID 12345 hermes.exe

Windows is holding the venv's launcher open (Hermes Desktop, a gateway, or
another hermes terminal). Close what is listed, or:

  hermes gateway stop          # stop the gateway service
  hermes dashboard --stop      # stop dashboards started by hand
  taskkill /PID 12345 /F       # the PID the update printed

The update also has escape hatches - `--force` skips the .exe check and
`--force-venv` skips the venv-holder check - but skipping the venv guard can
leave an install stranded between two versions, so stopping the listed
processes is the safe route.

Once the update finishes, the theme restores itself: within a minute on Windows
(the scheduled task), or as soon as you re-run run.bat / run.sh.

------------------------------------------------------------
SYSTEM & BROWSER COMPATIBILITY
------------------------------------------------------------

This skin targets the Hermes Agent web dashboard (served locally at
http://127.0.0.1:9119/sessions). It is visual-only and safe to apply.

Operating systems (where Hermes Agent runs):
  - Windows 10 / 11        -> use run.bat
  - macOS 12 Monterey +    -> use run.sh (double-click, or  bash run.sh)
  - Linux (any modern distro: Debian/Ubuntu, Fedora, Mint, Arch, etc.) -> bash run.sh
  - Python 3.8 or newer is required. If missing, the launcher installs it
    for you from the bundled python/ installers (no internet needed).

Browsers (the dashboard is viewed in your browser):
  - Google Chrome          - fully supported
  - Microsoft Edge         - fully supported
  - Mozilla Firefox        - fully supported
  - Safari / WebKit        - fully supported
  Tested headless in Chromium, Firefox, and WebKit with zero script errors.

Dashboard requirements:
  - Hermes Agent with the web dashboard feature enabled.
  - The skin injects a scoped LCARS layer (html.lcars-skin) and never modifies
    Hermes' own logic, config, sessions, API keys, or data.
  - Original dashboard is auto-backed-up on first apply; --restore returns it
    exactly.

Notes:
  - Wallpapers are original works by Moddy (MIT licensed) - see assets/ATTRIBUTION.md.
  - No network calls are made by the skin. No telemetry. No external fonts.
  - Stable chat view: the skin also installs a small "chat view stability" script on
    the dashboard's /chat tab. Switching away to another app or tab and coming back
    used to leave the chat somewhere other than where you left it. Now the view is
    recorded on the way out and restored on the way back, and nothing is written
    unless something actually moved. It never forces the view to the bottom, it gets
    out of the way as soon as you scroll, click or type, and it leaves live output
    alone. Run the installer with --no-chat-stability to turn it off; that choice is
    remembered, so the auto-heal keeps honouring it after a Hermes update. Use
    --chat-stability to turn it back on. The theme is unaffected either way.

------------------------------------------------------------
SUPPORT / CREDITS
------------------------------------------------------------

Made by Moddy  -  http://www.moddys.net
Free to use under the MIT License (see LICENSE).

  Thanks for checking out this release
  Enjoy the LCARS theme on your Hermes dashboard :) Cheers Moddy !

------------------------------------------------------------
